/*
 * Copyright (C) 2009-2011 Knowings
 *
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public License version 3
 * as published by the Free Software Foundation.
 *

 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.

 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 */
package com.knowings.tbs.trace;

import java.util.Date;

import com.knowings.tbs.TemporalDomain;
import com.knowings.tbs.persistence.IPersistentDescriptor;

/**
 * Convenience interface specifying the methods of a ITrace description container.
 * It enable access to some properties of a ITrace object like UID, owner, name, description and temporal domain. 
 * 
 * @author mbodin
 */
public interface ITraceDescriptor extends IPersistentDescriptor {

  /**
   * Method returning the owner property of the described trace.
   * @return a String object representing the owner. It shouldn't be null, at least empty.
   */
  public String getOwner();

  /**
   * Method returning the temporal domain kind of the described trace.
   * All obsels contained in the trace are related to the same temporal domain.
   * @return a TemporalDomain enum value. It shouldn't be null.
   */
  public TemporalDomain getTemporalDomain();

  /**
   * Method returning the object to be considered as the time origin for the date of the trace obsels.
   * The origin can either be an ISO-8601 date or an opaque string.
   * @return a string representation of the trace date origin.
   */
  public String getOrigin();

  /**
   * Computed property telling if the described trace is still up to date regarding its source traces and transformation.
   * @return true if no change has been made to the source traces and transformation since this trace generation
   */
  public boolean isObsolete();

  /**
   * Method telling if the described trace is a <code>IPrimaryTrace</code> instance or not.
   * @return true the described trace is a primary trace, false if it is a transformed trace
   */
  public boolean isPrimary();

  /**
   * Method returning the server time when the last update of this trace occurred.
   * This method is useful for clients that wish to update their data only if the trace
   * has been modified or to cope with the MODIFIED-SINCE attribute header in REST implementations.
   * @return the last modification date of this trace
   */
  public Date getLastModified();

}
